Bug 1627357 [wpt PR 22699] - Implement assert_implements and assert_implements_optional, a=testonly

Automatic update from web-platform-tests
Implement assert_implements and assert_implements_optional (#22699)

See web-platform-tests/rfcs#48 and
web-platform-tests/wpt#21971.

Note that this PR only implements the new methods; it does not port any
tests to use it or remove `assert_precondition` - that will be done in
follow-up PRs.
--

wpt-commits: d97d993e1c3977da9fe88ca2c867cd4466582eee
wpt-pr: 22699

Author: stephenmcgruer

testing/web-platform/tests/docs/writing-tests/testharness-api.md

@@ -313,40 +313,44 @@ NOTE: All asserts must be located in a `test()` or a step of an
 these places won't be detected correctly by the harness and may cause
 unexpected exceptions that will lead to an error in the harness.
 
-## Preconditions ##
+## Optional Features ##
 
-When a test would be invalid unless certain conditions are met, but yet
-doesn't explicitly depend on those preconditions, `assert_precondition` can be
-used. For example:
+If a test depends on a specification or specification feature that is OPTIONAL
+(in the [RFC 2119 sense](https://tools.ietf.org/html/rfc2119)),
+`assert_implements_optional` can be used to indicate that failing the test does
+not mean violating a web standard. For example:
 
 ```js
 async_test((t) => {
   const video = document.createElement("video");
-  assert_precondition(video.canPlayType("video/webm"));
+  assert_implements_optional(video.canPlayType("video/webm"));
   video.src = "multitrack.webm";
   // test something specific to multiple audio tracks in a WebM container
   t.done();
 }, "WebM with multiple audio tracks");
 ```
 
-A failing `assert_precondition` call is reported as a status of
-`PRECONDITION_FAILED` for the subtest.
+A failing `assert_implements_optional` call is reported as a status of
+`PRECONDITION_FAILED` for the subtest. This unusual status code is a legacy
+leftover from the deprecated `assert_precondition`; see the [RFC that renamed
+it](https://github.com/web-platform-tests/rfcs/pull/48).
 
-`assert_precondition` can also be used during test setup. For example:
+`assert_implements_optional` can also be used during test setup. For example:
 
 ```js
 setup(() => {
-  assert_precondition("onfoo" in document.body, "'foo' event supported");
+  assert_implements_optional("optionalfeature" in document.body,
+                             "'optionalfeature' event supported");
 });
-async_test(() => { /* test #1 waiting for "foo" event */ });
-async_test(() => { /* test #2 waiting for "foo" event */ });
+async_test(() => { /* test #1 waiting for "optionalfeature" event */ });
+async_test(() => { /* test #2 waiting for "optionalfeature" event */ });
 ```
 
-A failing `assert_precondition` during setup is reported as a status of
+A failing `assert_implements_optional` during setup is reported as a status of
 `PRECONDITION_FAILED` for the test, and the subtests will not run.
 
-See also the `.optional` [file name convention](file-names.md), which is
-appropriate when the precondition is explicitly optional behavior.
+See also the `.optional` [file name convention](file-names.md), which may be
+preferable if the entire test is optional.
 
 ## Cleanup ##
 
@@ -772,10 +776,6 @@ workers and want to ensure they run in series:
 
 ## List of Assertions ##
 
-### `assert_precondition(condition, description)`
-asserts that `condition` is truthy.
-See [preconditions](#preconditions) for usage.
-
 ### `assert_true(actual, description)`
 asserts that `actual` is strictly true
 
@@ -885,6 +885,13 @@ that the exception should have as its .constructor.  For example,
 
 `func` - a function that should throw
 
+### `assert_implements(condition, description)`
+asserts that a feature is supported, by checking if `condition` is truthy.
+
+### `assert_implements_optional(condition, description)`
+asserts that an optional feature is supported, by checking if `condition` is truthy.
+See [Optional Features](#optional-features) for usage.
+
 ### `assert_unreached(description)`
 asserts if called. Used to ensure that some codepath is *not* taken e.g.
 an event does not fire.
@@ -897,6 +904,9 @@ asserts that one `assert_func(actual, expected_array_N, extra_arg1, ..., extra_a
   allows multiple behaviours. Test authors should not use this method simply to hide
   UA bugs.
 
+### **DEPRECATED** `assert_precondition(condition, description)`
+Use `assert_implements` or `assert_implements_optional` instead.
+
 ## Utility functions ##
 
 ### **DEPRECATED** `on_event(object, event, callback)`

testing/web-platform/tests/fetch/metadata/portal.https.sub.html

@@ -12,7 +12,7 @@
 
   function create_test(host, expectations) {
     async_test(t => {
-      assert_precondition("HTMLPortalElement" in window, "Portals are not supported.");
+      assert_implements("HTMLPortalElement" in window, "Portals are not supported.");
 
       let p = document.createElement('portal');
       p.addEventListener('message', t.step_func(e => {

testing/web-platform/tests/html/semantics/embedded-content/the-video-element/resize-during-playback.html

@@ -12,7 +12,7 @@
 for (const format of ['mp4', 'webm']) {
   promise_test(async (t) => {
     const video = document.createElement('video');
-    assert_precondition(video.canPlayType(`video/${format}`), `${format} supported`);
+    assert_implements_optional(video.canPlayType(`video/${format}`), `${format} supported`);
 
     // Load the video and wait for initial resize event.
     video.src = `/media/400x300-red-resize-200x150-green.${format}`;

testing/web-platform/tests/resources/test/tests/unit/assert_implements.html

@@ -0,0 +1,43 @@
+<!DOCTYPE HTML>
+<html lang="en">
+<meta charset="utf-8">
+<script src="/resources/testharness.js"></script>
+<script src="/resources/testharnessreport.js"></script>
+<script src="/resources/test/tests/unit/helpers.js"></script>
+<title>assert_implements unittests</title>
+<script>
+'use strict';
+
+test(() => {
+  // All values in JS that are not falsy are truthy, so we just check some
+  // common cases here.
+  assert_implements(true, 'true is a truthy value');
+  assert_implements(5, 'positive integeter is a truthy value');
+  assert_implements(-5, 'negative integeter is a truthy value');
+  assert_implements('foo', 'non-empty string is a truthy value');
+}, 'truthy values');
+
+test_failure(() => {
+  assert_implements(false);
+}, 'false is a falsy value');
+
+test_failure(() => {
+  assert_implements(0);
+}, '0 is a falsy value');
+
+test_failure(() => {
+  assert_implements('');
+}, 'empty string is a falsy value');
+
+test_failure(() => {
+  assert_implements(null);
+}, 'null is a falsy value');
+
+test_failure(() => {
+  assert_implements(undefined);
+}, 'undefined is a falsy value');
+
+test_failure(() => {
+  assert_implements(NaN);
+}, 'NaN is a falsy value');
+</script>

testing/web-platform/tests/resources/test/tests/unit/assert_implements_optional.html

@@ -0,0 +1,43 @@
+<!DOCTYPE HTML>
+<html lang="en">
+<meta charset="utf-8">
+<script src="/resources/testharness.js"></script>
+<script src="/resources/testharnessreport.js"></script>
+<script src="/resources/test/tests/unit/helpers.js"></script>
+<title>assert_implements_optional unittests</title>
+<script>
+'use strict';
+
+test(() => {
+  // All values in JS that are not falsy are truthy, so we just check some
+  // common cases here.
+  assert_implements_optional(true, 'true is a truthy value');
+  assert_implements_optional(5, 'positive integeter is a truthy value');
+  assert_implements_optional(-5, 'negative integeter is a truthy value');
+  assert_implements_optional('foo', 'non-empty string is a truthy value');
+}, 'truthy values');
+
+test_failure(() => {
+  assert_implements_optional(false);
+}, 'false is a falsy value');
+
+test_failure(() => {
+  assert_implements_optional(0);
+}, '0 is a falsy value');
+
+test_failure(() => {
+  assert_implements_optional('');
+}, 'empty string is a falsy value');
+
+test_failure(() => {
+  assert_implements_optional(null);
+}, 'null is a falsy value');
+
+test_failure(() => {
+  assert_implements_optional(undefined);
+}, 'undefined is a falsy value');
+
+test_failure(() => {
+  assert_implements_optional(NaN);
+}, 'NaN is a falsy value');
+</script>

testing/web-platform/tests/resources/test/tests/unit/assert_object_equals.html

@@ -3,29 +3,11 @@
 <meta charset="utf-8">
 <script src="/resources/testharness.js"></script>
 <script src="/resources/testharnessreport.js"></script>
+<script src="/resources/test/tests/unit/helpers.js"></script>
 <title>Assertion functions</title>
 <script>
 'use strict';
 
-// The `assert_throws_*` functions cannot be used for this
-// purpose because they fail in response to AssertionError exceptions, even
-// when this is expressed as the expected error.
-function test_failure(fn, name) {
-  test(function() {
-    try {
-      fn();
-    } catch (err) {
-      if (err instanceof AssertionError) {
-        return;
-      }
-      throw new AssertionError('Expected an AssertionError, but');
-    }
-    throw new AssertionError(
-      'Expected an AssertionError, but no error was thrown'
-    );
-  }, name);
-}
-
 test(function() {
   assert_object_equals({}, {});
 }, 'empty objects');

testing/web-platform/tests/resources/test/tests/unit/helpers.js

@@ -0,0 +1,21 @@
+// Helper for testing assertion failure cases for a testharness.js API
+//
+// The `assert_throws_*` functions cannot be used for this purpose because they
+// always fail in response to AssertionError exceptions, even when this is
+// expressed as the expected error.
+function test_failure(fn, name) {
+  test(function() {
+    try {
+      fn();
+    } catch (err) {
+      if (err instanceof AssertionError) {
+        return;
+      }
+      throw new AssertionError('Expected an AssertionError, but');
+    }
+    throw new AssertionError(
+      'Expected an AssertionError, but no error was thrown'
+    );
+  }, name);
+}
+

testing/web-platform/tests/resources/testharness.js

@@ -1848,6 +1848,49 @@ policies and contribution forms [3].
     }
     expose(assert_any, "assert_any");
 
+    /**
+     * Assert that a feature is implemented, based on a 'truthy' condition.
+     *
+     * This function should be used to early-exit from tests in which there is
+     * no point continuing without support for a non-optional spec or spec
+     * feature. For example:
+     *
+     *     assert_implements(window.Foo, 'Foo is not supported');
+     *
+     * @param {object} condition The truthy value to test
+     * @param {string} description Error description for the case that the condition is not truthy.
+     */
+    function assert_implements(condition, description) {
+        assert(!!condition, "assert_implements", description);
+    }
+    expose(assert_implements, "assert_implements")
+
+    /**
+     * Assert that an optional feature is implemented, based on a 'truthy' condition.
+     *
+     * This function should be used to early-exit from tests in which there is
+     * no point continuing without support for an explicitly optional spec or
+     * spec feature. For example:
+     *
+     *     assert_implements_optional(video.canPlayType("video/webm"),
+     *                                "webm video playback not supported");
+     *
+     * @param {object} condition The truthy value to test
+     * @param {string} description Error description for the case that the condition is not truthy.
+     */
+    function assert_implements_optional(condition, description) {
+        if (!condition) {
+            // Due to the difficulty of changing logging statuses, we re-use
+            // the PRECONDITION_FAILED status for assert_implements_optional.
+            // See the RFC: https://github.com/web-platform-tests/rfcs/pull/48
+            //
+            // TODO(smcgruer): Once assert_precondition is removed, rename the
+            // exception and move this comment to where PRECONDITION_FAILED is used.
+            throw new PreconditionFailedError(description);
+        }
+    }
+    expose(assert_implements_optional, "assert_implements_optional")
+
     function assert_precondition(precondition, description) {
         if (!precondition) {
             throw new PreconditionFailedError(description);